Debian tutorial¶

This document is intended for beginners using the Quectel Pi H1 smart single-board computer and is designed to help them quickly learn common Debian operations and development tasks. It covers file attributes and permissions, file management, text editing, and package management, making it suitable for users with no prior experience and those new to Linux.

File attributes and permissions¶

Learn about Linux file types, ownership, and permission bits. Use ls -l to view file attributes, and use chown and chmod to manage ownership and access permissions.

In Linux, files have attributes such as the filename, size, owner, group, access permissions, type, and modification time. Understanding these attributes helps you determine why a script cannot be executed, a directory is not writable, or sudo is required to modify a system configuration file.

How to view file attributes¶

The most common way to view file attributes is as follows:

ls -l

To also display hidden files and show file sizes in a more readable way, run the following command:

ls -lah

A typical output is shown below:

-rwxr-xr-- 1 pi pi 2048 Jun 22 10:30 demo.sh

This information can be split into the following parts:

Field	Example	Description
File type and permissions	-rwxr-xr–	The first character indicates the file type, and the remaining nine characters indicate permissions.
Number of links	1	The number of directory entries pointing to the file.
Owner	pi	File owner.
Group	pi	The group that owns the file.
Size	2048	File size. Unit: bytes (default).
Modification time	Jun 22 10:30	Last modification time.
File name	demo.sh	File name.

File type identification¶

The first character in the permission string indicates the file type:

For example:

drwxr-xr-x: Directory.
-rw-r–r–: Regular file.
lrwxrwxrwx: Symbolic link.

Permission bit structure description¶

The nine characters from positions 2 through 10 are divided into three groups:

rwx r-x r--
|   |   |
|   |   +-- Other users (others) permissions
|   +------ Group (group) permissions
+---------- Owner (owner) permissions

Each set of permissions contains the following characters:

Symbol	Meaning
r	Readable
w	Writable
x	Executable
-	No permission

For example:

rw-r–r–: The owner can read and write the file, while the group and other users can only read it.
rwxr-xr-x: The owner can read, write, and execute the file, while the group and other users can read and execute it.

chown: manage owner and group¶

If a file is owned by the wrong user or group, use chown to change its ownership.

Basic syntax:

sudo chown [options] user[:group] file_or_directory

Common examples:

Change the file owner to pi:

sudo chown pi demo.sh

Change both the owner and group:

sudo chown pi:pi demo.sh

Recursively change the owner and group of the directory:

sudo chown -R pi:pi /home/pi/project

Change only the group:

sudo chown :pi /home/pi/project/config.json

Quectel Pi H1 typical application scenarios

After files are extracted or copied using sudo, their owner becomes root, preventing the regular user pi from editing them.
If the permissions of a project directory copied from an external device do not match those of the current user, adjust them accordingly.

chmod: manage access permissions¶

Use chmod when a file is readable but not writable, or when a script cannot be executed.

Basic syntax:

chmod [options] permissions file_or_directory

Symbolic mode

The format is as follows:

[ugoa][+-=][rwx]

Where:

u represents the owner.
g indicates the group.
o means other users.
a means all users.

Common examples:

Add execute permissions for the owner:

chmod u+x demo.sh

Add read permission for all users:

chmod a+r demo.txt

Remove write permissions for other users:

chmod o-w demo.txt

Numeric mode

Permissions can also be expressed in numerical form, for example:

chmod 755 demo.sh
chmod 644 notes.txt

The three digits correspond to:

chmod 754 demo.sh
    | | |
    | | +-- Other users (others) permissions
    | +---- Group (group) permissions
    +------ Owner (owner) permissions

Each rwx group consists of three permission bits: r, w, and x.

Is r (read permission) enabled?
Is w (write permission) enabled?
Is x (execution permission) enabled?

These three permission bits can be represented either by additive values or as a three-bit binary number:

The corresponding relationship is as follows:

Permission bit	Binary bit	Decimal weight
r	100	4
w	10	2
x	1	1

Therefore, the number of a set of permissions is essentially the sum of the weights of each enabled permission bit:

r– = 100 = 4
rw- = 110 = 4 + 2 = 6
r-x = 101 = 4 + 1 = 5
rwx = 111 = 4 + 2 + 1 = 7
— = 000 = 0

Example¶

Add execution permissions to the script

chmod u+x start.sh
./start.sh

Protect private configuration files

chmod 600 ~/.ssh/config

File and directory management¶

Learn the most commonly used Linux file and directory commands: pwd, cd, ls, mkdir, rmdir, cp, rm, and mv, as well as file-viewing commands such as cat and tail.

In Linux, many routine operations involve paths and directories. Common file and directory commands are used to view logs, navigate project directories, copy model files, and remove unneeded resources.

Basic concepts of paths and directories¶

Current working directory¶

A terminal session always has a current working directory. Most commands work in the current directory by default, so it’s important to know the location.

View the current directory:

pwd

Path representation¶

Absolute path: Start from the root directory /, such as /home/pi/project.
Relative path: Relative to the current directory, such as project/src.

Common special notations:

.indicates the current directory.
… represents the parent directory.
~ represents the current user’s home directory, such as /home/pi.

Commonly used system directories¶

In Debian, users commonly work with the following directories:

Directory	Function
/etc	System configuration file.
/opt	Third-party applications or custom programs.
/var/log	System log.
/tmp	Temporary files.

Common commands¶

ls: view directory contents¶

The ls command lists the files and subdirectories in a specified directory.

Example:

# View the contents of the current directory
ls

# View all files in the current directory, including hidden files
ls -la

# View more readable file sizes
ls -lh

# View files sorted by time
ls -ltr

cd: change directories¶

The cd command changes the current working directory to the specified path.

cd [dirName]
# dirName: target directory, which can be a relative path or an absolute path.

Example:

# Switch to the usr directory
cd /usr

#Return to the parent directory
cd ..

# Return to user home directory
cd ~

# Return to the previous working directory
cd -

mkdir and rmdir: create and delete directory¶

The mkdir command creates a directory, while rmdir removes an empty directory.

# -p ensures that the directory path exists, if it does not exist it will be created automatically
mkdir [-p] dirName

# -p If the parent directory becomes empty due to deletion of subdirectories, delete them together.
rmdir [-p] dirName

Example:

# Create a logs directory in the current directory
mkdir logs

# Automatically create non-existent parent directory project/data
mkdir -p project/data/raw

# Delete the logs directory, which must be empty
rmdir logs

cp: copy files and directories¶

Run the cp command to copy a file or directory from a source path to a destination path.

cp [options] source_file destination_file

Example:

#Copy the file source.txt to backup.txt
cp source.txt backup.txt

#copy directory
cp -r project project_backup

mv: move and rename¶

The mv command renames a file or directory, or moves it to another location.

# Move app.log to the /tmp/ directory
mv app.log /tmp/

# Rename the old_name.txt file to new_name.txt
mv old_name.txt new_name.txt

# Rename the directory, rename the dataset directory to dataset_old
mv dataset dataset_old

rm: delete file and directory¶

The rm command removes files or directories.

#Delete the file demo.txt
rm demo.txt

#Delete the demo_dir directory and subdirectories
rm -r demo_dir

#Force removal without prompting
rm -rf demo_dir

Note

rm -rf is a high-risk command, and deleted data cannot be recovered. Before running it, use pwd and ls to confirm the target path.

cat and tail: view file content¶

cat

The cat command concatenates files and writes their contents to standard output. It is commonly used to view file contents or combine multiple files.

#View the contents of the README.md file
cat README.md

#View with line number display
cat -n app.py

tail

The tail command displays the end of a file.

# The last 10 lines of system logs are displayed by default.
tail /var/log/syslog

# Check the last 50 lines of the system log /var/log/syslog
tail -n 50 /var/log/syslog

# Follow the log in real time
tail -f /var/log/syslog

Basic operation examples¶

Create and enter a project directory¶

mkdir -p ~/project/demo
cd ~/project/demo
pwd

Back up configuration files¶

cp -i /etc/hosts ~/hosts.bak

Clean up temporary directory¶

rm -r ~/project/demo/tmp

Text editing¶

When developing with Quectel Pi H1, you may need to modify configuration files, edit scripts, or adjust service parameters. Commonly used text editors in the terminal environment include Vim and nano. This section introduces both editors so that you can choose the one that best suits your needs.

Vim editor¶

Vim is an enhanced version of the vi editor. It supports syntax highlighting, search and replace, batch editing, and other features. It is suitable for local terminals, serial terminals and SSH sessions.

If the system prompts that the command cannot be found, you can first execute the following command to install:

sudo apt update
sudo apt install vim

Vim operating modes¶

According to common usage, Vim has three primary operating modes:

Mode	Function	How to enter
Command mode	Move cursor, copy, delete, save, exit	Enter by default after opening the file.
Input mode	Enter and modify text	Press i, a, o in command mode.
Command line mode	Execute commands such as save, exit, find and replace, etc.	Press : in command mode.

The switching logic between these three modes is as follows:

After opening a file, it enters command mode by default.
When you need to input content, switch to input mode.
Switch to command line mode when you need to save, exit, or perform a find and replace.

Basic operations¶

Open or create a file

vim notes.txt

If the file does not exist, Vim will automatically create a new file.

Enter input mode

Press any of the following keys in command mode:

Key	Function
i	Enter input mode at the current cursor position.
a	Enter input mode after the current cursor position.
o	Open a new line below the current line and enter input mode.

Text entry

After entering input mode, you can enter characters like a normal editor.

Return to command mode

Press the Esc key to return to command mode.

Save and exit

In command mode, press : to enter command-line mode, and then enter and execute the appropriate command:

Command	Function
:w	save
:q	Exit
:wq	Save and exit
:q!	Do not save, force quit

Common operating instructions¶

Common instructions in command mode

Key	Function
h j k l	Move cursor left, down, up, right
x	Delete current character
dd	Delete the current line
yy	copy current line
p	Paste after the current line
u	Undo
Ctrl+r	Redo
/keyword	Search forward
n	Jump to next match

Common commands in command line mode

Command	Function
:set nu	Show line numbers
:set nonu	Hide line numbers
:%s/old/new/g	Replace all occurrences in the file
:1,10s/old/new/g	Replace lines 1 to 10

Example¶

The following is an example of creating a simple script:

vim hello.sh

Press i to enter input mode, and then enter the following content:

#!/bin/bash
echo "Hello Quectel Pi H1"

Press Esc to return to command mode, then enter :wq to save and exit.

Then add execution permissions to the script:

chmod u+x hello.sh
./hello.sh

Edit system files¶

To edit a file in a regular user’s home directory, run:

vim ~/notes.txt

System configuration files typically require elevated privileges. Run Vim with sudo:

sudo vim /etc/hostname

It is recommended to back up the original file first:

sudo cp /etc/hostname /etc/hostname.bak
sudo vim /etc/hostname

Troubleshooting common problems¶

Unable to exit Vim

Most of the time, you are still in input mode. Press the Esc key first, then enter :q or :wq.

Permission denied when saving

This indicates that the current file requires administrator privileges. Exit Vim, then reopen it using sudo vim <filename>.

Chinese characters or indentation are displayed incorrectly

These issues are usually related to terminal font or file encoding. Use UTF-8 encoding whenever possible, and ensure that the font used by the graphical terminal supports Chinese characters.

nano editor¶

Overview¶

nano is a lightweight terminal text editor with a simple and intuitive interface. It requires no mode switching, making it suitable for quickly editing configuration files and for users who are unfamiliar with Vim.

If nano is not installed, run the following commands:

sudo apt update
sudo apt install nano

Basic operations¶

Open or create a file

nano notes.txt

If the file does not exist, nano will automatically create a new file. Once the file is opened, you can enter and edit text directly without switching modes.

Edit text

After opening the file, you can directly enter characters at the cursor position and use the arrow keys to move the cursor.

Save file

Press Ctrl+O (the letter O), nano will prompt to confirm the file name, press Enter key to confirm saving.

Exit editor

Press Ctrl+X to exit. If there are unsaved modifications to the file, nano will ask whether to save them:

Press Y to save and exit.
Press N to exit without saving.
Press Ctrl+C to cancel the exit operation.

Commonly used shortcut keys¶

nano displays common keyboard shortcuts at the bottom of the screen. The ^ symbol represents the Ctrl key.

Shortcut keys	Function
Ctrl+O	Save file
Ctrl+X	Exit
Ctrl+K	Cut current line
Ctrl+U	Paste the cut content
Ctrl+W	Search text
Ctrl+	Search and replace
Ctrl+G	View help
Ctrl+C	Show current cursor position
Alt+U	Undo
Alt+E	Redo
Ctrl+A	Move to beginning of line
Ctrl+E	Move to end of line
Ctrl+Y	Page up
Ctrl+V	Page down

Search and replace¶

Search text

Press Ctrl+W, enter the search term, and press Enter to jump to the first match. Press Ctrl+W and Enter again to jump to the next match.

Search and replace

Press **Ctrl+**, enter the search string, and press Enter. Then enter the replacement string and press Enter again. The nano editor will prompt you to confirm each replacement:

Press Y to replace the current match.
Press N to skip the current match.
Press A to replace all matches.

Example¶

Take creating a simple script as an example:

nano hello.sh

Enter the following directly:

#!/bin/bash
echo "Hello Quectel Pi H1"

Press Ctrl+O to save, press Enter to confirm the filename, and then press Ctrl+X to exit.

Then add execution permissions to the script:

chmod u+x hello.sh
./hello.sh

Edit system files¶

When editing system configuration files, you also need to use sudo permissions:

sudo nano /etc/hostname

Software downloads and updates¶

On Debian, software is typically installed using APT or dpkg. Understanding their respective roles helps distinguish between installing packages from repositories and manually installing local .deb packages.

This section introduces the basic methods for installing and updating software on Debian, so that users can understand commands such as apt install when setting up their development environment.

For details about APT, common commands, and repository configuration, see Software update.

Overview of APT and dpkg¶

In Debian systems, software installation mainly relies on the following two types of tools:

Tools	Function	Typical scenario
APT	Find and download software from software sources and automatically handle dependencies	Install software and update system online.
dpkg	Install local .deb package directly	Manually install the installation package provided by the manufacturer.

APT is a high-level package management tool that retrieves packages from repositories and resolves dependencies automatically. dpkg is a low-level tool used to install local .deb packages and does not resolve dependencies automatically.

Common APT commands¶

apt update¶

Update the package list. This command is used to refresh the local package index. This command does not install or upgrade any software, it is only used to update information about available software packages and their latest versions in the software repository.

Run the apt update command before installing software or upgrading the system.

sudo apt update

apt upgrade¶

Upgrade installed software packages. This command will upgrade all installed software packages on the system to the latest version available in the software repository.

sudo apt upgrade

The usual procedure is to run update first, followed by upgrade:

sudo apt update
sudo apt upgrade

apt install¶

The apt install command is the most commonly used command for installing packages. It retrieves the specified package from the configured repositories, installs it, and automatically resolves its dependencies.

sudo apt install package_name

When setting up a development environment, you will often use commands such as the following:

sudo apt install python3       # Install Python 3
sudo apt install git           # Install Git
sudo apt install vim           # Install Vim editor

#Multiple packages can be installed at once:
sudo apt install python3 git vim

apt remove¶

The apt remove command removes the specified package from the system.

sudo apt remove package_name